---
title: Execute a single conversion (converter template)
summary: Run the shared conversion pipeline around each format converter's ConvertItem hook.
status: draft
owner: SAIF Doc Gen
last_reviewed: 2026-09-17
library: PdfAPI.SyncFusionCore
reference_type: package
operation_id: OP-SFC-002
trigger: Called by ConverterFactory.Convert
---

# Execute a single conversion (converter template)

This operation is the template-method core shared by all eight format converters: it owns stream disposal, timing, exception capture, and `PdfResult` assembly, while delegating the actual byte-level conversion to the subclass's `ConvertItem` hook.

| Field | Value |
| --- | --- |
| **Operation ID** | OP-SFC-002 |
| **Trigger** | Called by [Convert a source document to PDF](convert-source-document-to-pdf.md) |
| **Inputs** | Source `Stream`, `ConvertRequest` |
| **Outputs** | `PdfResult` |
| **Primary components** | `BaseConverter.Convert` |
| **Entry point** | `PdfApi.SyncFusionCore\Convert\BaseConverter.cs` |

## Steps

1. Take ownership of the stream in a `using` block, guaranteeing disposal on every path.
2. Call `ConfigureConverter(request.Options)` — the per-format configuration hook. All eight
   concrete converters implement this as an empty method, so the hook is currently inert.
3. Create `new PdfResult(ConversionType, request)` and stamp `PdfProcessorType = Syncfusion` ([BR-SFC-006](../business-rules.md#br-sfc-006-result-stamped-syncfusion-processor)).
4. Start a `Stopwatch`.
5. Call the subclass `ConvertItem(stream, request)` and wrap the returned bytes with
   `Document.Load(bytes, "pdf")` (`PdfAPI.Core`).
   - The subclass hook is one of: [Word document to PDF](word-document-to-pdf.md),
     [Excel workbook to PDF](excel-workbook-to-pdf.md), [RTF document to PDF](rtf-document-to-pdf.md), [Plain text to PDF](plain-text-to-pdf.md), [Raster image to PDF](raster-image-to-pdf.md), [TIFF to multi-page PDF](tiff-to-multi-page-pdf.md), [HTML to PDF](html-to-pdf.md), or [PDF pass-through or PDF/A upgrade](pdf-passthrough-or-pdfa-upgrade.md), depending on which converter constructed this `BaseConverter` instance.
6. Set `Status = Succeeded` when `Document?.File` is non-null, otherwise `Failed` ([BR-SFC-007](../business-rules.md#br-sfc-007-conversion-success-requires-non-null-document)); copy `request.Options` onto the result.
   - If [PDF pass-through or PDF/A upgrade](pdf-passthrough-or-pdfa-upgrade.md) returns `null` (no
     matching branch), this step marks the result `Failed`.
7. Set `OutputFormat` to `PdfA` when `request.Options.IsPdfa`, otherwise `Pdf` ([BR-SFC-008](../business-rules.md#br-sfc-008-output-format-reflects-pdf%2Fa-option)).
8. Parse `request.SourceSystemId` with `long.TryParse` into `result.ImageId`; a non-numeric or null
   value yields `0` ([BR-SFC-009](../business-rules.md#br-sfc-009-source-system-id-parsed-to-numeric-image-id)).
9. On any exception: record `ex.Message` in `result.Message` and set `Status = Failed`. No rethrow,
   no logging ([BR-SFC-010](../business-rules.md#br-sfc-010-conversion-exceptions-captured-not-rethrown)).
10. In `finally`, stop the stopwatch and store `sw.Elapsed` on the result; return the result.

## Process flow

The following diagram visualizes this operation's control flow.

```mermaid
flowchart TD
	Start(["Convert called with<br>stream and ConvertRequest"]) --> Dispose["Take ownership of stream<br>in using block"]
	Dispose --> Configure["Call ConfigureConverter<br>currently a no-op hook"]
	Configure --> Init["Create PdfResult,<br>stamp Syncfusion processor"]
	Init --> StartTimer[Start Stopwatch]
	StartTimer --> Try{"ConvertItem throws?"}
	Try -->|No| WrapDoc["Wrap bytes with<br>Document.Load"]
	WrapDoc --> DocNull{"Document.File<br>non-null?"}
	DocNull -->|Yes| Succeed["Status = Succeeded"]
	DocNull -->|No| Fail1["Status = Failed"]
	Succeed --> SetFormat["Set OutputFormat<br>from Options.IsPdfa"]
	Fail1 --> SetFormat
	SetFormat --> ParseId["Parse SourceSystemId<br>to ImageId"]
	Try -->|Yes| Catch["Catch exception:<br>Status = Failed,<br>Message = ex.Message"]
	ParseId --> StopTimer["Stop Stopwatch,<br>store Elapsed"]
	Catch --> StopTimer
	StopTimer --> Result([Return PdfResult])
```

## Failure and edge-case behavior

- Every exception raised by `ConvertItem` is caught here; none of the eight format converters need
  their own exception handling to satisfy the caller's contract.
- A converter that legitimately returns `null` bytes (only [PDF pass-through or PDF/A upgrade](pdf-passthrough-or-pdfa-upgrade.md), when neither branch applies) is treated the same as a
  failure, not as a distinct outcome.

## Related documentation
- [Operations and processes](../operations-processes.md)
- [Business rules](../business-rules.md)

## Sources
- `PdfApi.SyncFusionCore\Convert\BaseConverter.cs`